01. PURPOSE
--------------------
The program PLANEPH is an executable DOS program for PC which computes the most usual ephemeris of planets between 1900 and 2100.

It has to be regarded as an example for the use of the planetary series built by frequency analysis (Chapront, 1995).

The representations of the planetary motions are based on numerical integration DE403 provided by Jet Propulsion Laboratory (Standish et al., 1995).

02. FILES
---------------
README : ascii : Information.
planeph.doc : ascii : User guide (this document).
planeph.exe : binary : Executable program.
planeph.tab : binary : Planetary tables.
planeph.loc : binary : Locations coordinates.

03. INSTALLATION
----------------------------
The program uses two data sets :

Planetary tables : planeph.tab
Locations coordinates : planeph.loc

Procedure of installation : create a directory on disk (for example PLANEPH) and copy the three following files in binary mode :
Executable program : planeph.exe.
Planetary tables : planeph.tab.
Locations coordinates : planeph.loc.

The program runs under DOS 6.2 operating system and following versions. It needs an arithmetic processor and it is necessary to configure the system with the file ANSI.SYS : device=ANSI.SYS.

04. USE
------------
The program starts in the directory defined by the procedure of installation with the command : planeph. The commands of the program PLANEPH are entered on the keyboard and the user makes his choice with menus displayed on the screen.

The main menu shows commands to perform the following items :
- Define the specifications of the ephemeris,
- Run the computation,
- Refresh the current specifications, setting back the standard options,
- Quit the program.

It is advised to choose the specifications of the ephemeris in this order :

E : Ephemeris
B : Body
V : Variables
F : Reference frame
O : Options
D : Date
I : Tab intervals
L : Location
T : Time scale
U : Units
R : Results

The other commands are :
X : to executes the computation,
Z : to set back the standard options,
Q : to quit the application.

Before using the execute command (X), the user is able to modify all the specifications of the current ephemeris.
Various menus allow the choices of the specifications. When using the program the first time the menu Ephemeris" (E) is displayed.

To choose the specifications of the ephemeris, two modes are available :
- Choose a code among a set of choices (ex : M for Mercury).
- Enter a numeric quantity in a given format (ex : 19960101 for the Date).

The user can always Quit the current menu and Return to the main menu with the keys "Q" or "R". When the choices of specifications require multiple answers, one has to Confirm the whole set of choices with the key "C". By default the specifications are :

E : Ephemeris : Geometric coordinates.
B : Body : Earth.
V : Variables : Heliocentric Rectangular coordinates.
F: Frame : Fixed Equatorial Frame J2000.00 (JD2451545.00000).
O : Options : Positions.
D : Date : Current date of the computer at 0h.
I : Tab Intervals : 1 day.
L : Location : Paris (France) 48d50'N 2d20'E.
T : Time scale : Dynamical Time (DT).
U : Units : Astronomical unit (au).
R : Results : Interactive display of the Results.

In order to avoid inconsistencies, a chosen specification can modify automatically one another specification. For example, when choosing the Sun as a Body (B) even though the Variable (V) is Heliocentric, automatically, the variable becomes Geocentric.

05. EPHEMERIS (E)
----------------------------
The user is able to choose between 9 types of ephemeris;

E1 : Geometric coordinates.
E2 : Apparent coordinates (geocentric).
E3 : Astrometric coordinates (geocentric).
E4 : Topocentric coordinates.
E5 : Physical ephemeris.
E6 : Osculating elements.
E7 : Rising, Setting, Transit times.
E8 : Sidereal time, Obliquity, Nutation.
E9 : Calendar.

Explanations about the 8 first types of ephemeris (E1 to E8) are given in the other paragraphs.

The calendar (E9) contains the following informations :
- Julian dates.
- Day of the week.
- Number of the day and week in the year.
- Difference DT-UT (estimate) : Dynamical Time minus Universal Time.
- Equation of Time AST - MST : Apparent Solar Time minus Mean Solar Time.

06. BODY (B)
-------------------
Depending on the chosen type of ephemeris, the user selects one of the following INSTALLATION bodies :

M : Mercury J : Jupiter P : Pluto
V : Venus S : Saturn B : Earth-Moon Barycenter
E : Earth U : Uranus H : Sun
A : Mars N : Neptune

Earth-Moon Barycenter is available only for geometric coordinates (E1) and osculating elements (E6).

07. VARIABLES (V)
----------------------------
One has to specify variables in case of the following ephemeris :

* Geometric coordinates (E1) :
V1 : Geocentric / V2 : Heliocentric / V3 : Barycentric.
V4 : Rectangular / V5 : Spherical.

* Topocentric coordinates (E4) :
V1 : Apparent / V2 : Astrometric /
V3 : Horizontal / V4 : Hour angle and declination.

* Physical ephemeris (E5) :
V1 : Phases, Magnitudes, Diameters /
V2 : Planetocentric coordinates of the Earth.

* Osculating elements (E6)
V1 : Elliptic elements, set 1 : a, lambda, e, i, omega, pi /
V2 : Elliptic elements, set 2 : a, lambda, h, k, p, q.

* Rising, Setting and Transit times (E7) :
V1 : Rising and Setting / V2 : Transit / V3 : Twilight.

* Sidereal time, Obliquity, Nutation (E8) :
V1 : Greenwich sidereal time (UT) / V2 : Obliquity and Nutation.

Remarks :

The apparent coordinates (E2) and astrometric coordinates (E3) are geocentric and spherical variables.

The topocentric coordinates, apparent (E4-V1) and astrometric (E4-V2), are spherical variables.

The plane of reference (Equator or Ecliptic) for geometric coordinates (E1), apparents coordinates (E2 and E4-V1) and astrometric coordinates (E3 and E4-V2) depends on the chosen reference frame (see Frame (F) below).

With the geometric spherical coordinates (E1-V5), is also provided :
- geometric distance between the body and the center of the frame.

With the apparent geocentric coordinates (E2), are also provided :
- geometric distance Earth-Body,
- horizontal equatorial parallax.

With the astrometric geocentric coordinates (E3), are also provided :
- geometric distance Earth-Body,
- light time between Body and Earth.

With the apparent topocentric coordinates (E4-V1), is also provided :
- geometric distance Location-Body.

With the astrometric topocentric coordinates (E4-V2), are also provided :
- geometric distance Location-Body,
- light time between Body and Location.

The horizontal topocentric coordinates (E4-V3) are : azimuth, altitude and zenith distance (apparent coordinates).
Azimuth is measured toward East or West from the South direction and it is not computed at the Earth'poles or when the body is at the zenith. Altitude and zenith distance take into account the astronomical refraction when body is above the horizon (Radau's tables).

The topocentric coordinates (E4-V4) are : hour angle, declination (apparent coordinates) and the local apparent sidereal time.

The physical ephemeris (E5-V1) are : phase, phase angle, defect of illumination, visual magnitude and apparent diameter.
For Mercury and Venus, magnitude is not computed when elongations are respectively greater than 125 and 170 degrees.

The planetocentric coordinates (E5-V2) are : planetographic longitude and latitude of sub-Earth point and position angle of the axis of rotation
(north pole of the body).

The ephemeris for Sidereal Time (E8-V1) are : Greenwich Sidereal Time (mean and apparent), and equation of the equinoxes in UT (Universal Time).

The ephemeris for Obliquity and Nutation (E8-V2) are : mean obliquity of date, true obliquity, and nutations in longitude and obliquity.

08. FRAME (F)
---------------------
The type of frame has to be defined in the following cases :

* Geometric coordinates (E1).
Frame : fixed of a Julian epoch / mean of date / true.
Frame : equatorial / ecliptic.

* Geocentric or topocentric apparent coordinates (E2) (E4-V1).
Frame : equatorial / ecliptic.

* Geocentric or topocentric astrometric coordinates (E3) (E4-V2).
Frame : fixed of a Julian epoch / mean of date.
Frame : equatorial / ecliptic.

* Osculating elements (E6).
Frame : fixed of a Julian epoch / mean of date.

Remarks :

A frame is defined with the equinox and the reference plane : equator or ecliptic.

A fixed frame of a Julian epoch is defined with the fixed equinox and the fixed reference plane (equator or ecliptic) at this Julian epoch, whatever may be the date of the ephemeris.

The mean frame of date is defined with the mean equinox and the mean reference plane of date. Here, one takes into account the precessional motion of the frame at the current date of the ephemeris.

The true frame is defined with the true equinox and true equator of date in case of equatorial coordinates, and with the true equinox and mean ecliptic of date in case of ecliptic coordinates. Here, one takes into account precession and nutation at the current date of the ephemeris.

For the fixed frame of a Julian epoch, the user has to define the chosen Julian epoch (for example 2000.0 for J2000). Generally, the Julian epoch Jxxxx.xx and the corresponding Julian Day JD are related with : xxxx.xx = 2000.0 + (JD-2452545.0)/365.25.

In case of apparent coordinates (E2) (E4-V1) the frame is always true.

The following coordinates :
- geometric, spherical coordinates (E1-V5),
- apparent, geocentric and topocentric coordinates (E2 and E4-V1),
- astrometric, geocentric and topocentric coordinates (E3 and E4-V2), are :
- right ascension and declination when the plane of reference is Equator,
- longitude and latitude when the plane of reference is Ecliptic.

In case of osculating elements (E6) the frame is always ecliptic.

09. OPTIONS (O)
-------------------------

Options of an ephemeris computation have to be defined in the following cases :

* Geometric coordinates (E1) :

Positions /
Positions and absolute velocities /
Positions and relative velocities.

One has to distinguish between absolute and relative velocities when the reference frame is not fixed (mean of date or true).
Velocities are called "absolute" when they are not corrected with the velocity of the moving reference frame.
Velocities are called "relative" when they are corrected - with the precessional velocity in case of mean frame of date, - with the velocities of precession and nutation in case of true frame.

* Rising and setting times (E7-V1)

Disk center / Upper limb / Lower limb.
Horizontal astronomical refraction values : 36.6' or 34'.

36.6' horizontal astronomical refraction is given by Radau's tables to a zero apparent altitude, under the following conditions :
Latitude : 45 degrees ; Altitude : 0m; Temperature 0 degree C;
Pressure 760 mm (0 degree C)

34' horizontal astronomical refraction is mostly used in nautical ephemeris.

* Twilights (E7-V3) :

Civil / Nautical / Astronomical.

Twilight ephemeris are computed, without correction of refraction, when the altitude of the solar disk center, at the observer location, is equal to :

10. DATE (D)
-------------------
Length of validity covers the period :
Beginning : Jan. 1 1900 0h (JD2415020.5).
End : Jan. 1 2099 0h (JD2487704.5).

The initial date of the computation can be chosen in four different ways :

1. Date (format YYYYMMDD).
Example : 19960408 (1996 Apr. 8).

2. Hour (format HHMMSS).
Example : 60200 (6h 2m 0s).

3. Date and hour (format YYYYMMDD.HHMMSS).
Example : 20101001.170945 (2010 Oct. 1 17h 9m 45s).

4. Julian date.
Example : 2451545.00000 (2000 Jan. 1 12h).

In case of rising, setting, transit and twilight times, the initial date of the computation is given at 0h; the formats 1 (Date) and 4 (Julian date) are only useful.
Example : Date = 19970714 or Julian date = 2450643.5 (1997 Jul. 14 0h).

11. TAB INTERVALS (I)
----------------------------------
Tab intervals between two running dates should not overstep 999 days. They are given in a format which is related to the format which has been chosen previously for the initial date of the computation.

If the initial date is a calendar date (YYYYMMDD), tab intervals are given under the form : DDD.HHMMSS.
Example : 0.023000 for 2h 30m 0s.

If the initial date is a Julian date, tab intervals are given under the form : DDD.ddddd.
Example : 1.5 for 1.5 day.

Exception : For rising, setting, transit, twilight times (E7), tab intervals are always under the form : DDD (integer).
Example : 5 for 5 days.

12. LOCATION (L)
--------------------------
The choice of a location has to be done in the case of topocentric coordinates (E4), rising, setting, transit and twilight times (E7).

Three possibilities are afforded :

* Name of a location

The user has to enter the name of a location (between 3 to 30 characters). He is not obliged to input the complete name.

Caution! The spelling of the locations names is in french.

- If the chosen location is found by the program the user has to confirm his choice.
- If the program finds several homonyms, the user is requested to choose among a proposed list of 15 names at most.
- If the name is unknown or if it exists more than 15 homonyms, the user has to reenter his choice or to quit the current menu.

* Geographic zone

The user has to choose a location after selecting a geographic zone : continent, country, french department.

* Coordinates of a location (terrestrial longitude and latitude)

The latitude has to be written with the format DD.MM, negatively southward and positively northward, between -90.00 and +90.00.
Example : -7.5 for 7 degrees and 50 minutes South.
0.02 for 0 degree and 2 minutes North.

The longitude of the location has to be written with the format DDD.MM, negatively westward and positively eastward between -180.00 and +180.00.
Example : -150.33 for 150 degrees and 33 minutes West.
16 for 16 degrees and 0 minute East.

Remark :
The meridian origin of the longitudes depends on the choice of time scale (see hereunder paragrah).

13. TIME SCALE (T)
-----------------------------
Three possibilities are afforded to define the time scale of the computations :

* Dynamical Time (DT)

This time belongs to the family of time scales introduced in 1984 to replace "Ephemeris Time" (ET) which is commonly used in theories of Celestial Mechanics.
We use Barycentric Dynamical Time (TDB) when ephemeris is referred to the barycenter of solar system, and Terrestrial Time (TT) for geocentric ephemeris.
Within the precision of the ephemeris provided by PLANEPH, Dynamical Time (DT) can be identified to Terrestrial Time (TT) which is physically realized by International Atomic Time (TAI). We have the relation : TT = TAI + 32.184s.

* Universal Time (UT)

It is the civil time of Greenwich meridian. Within one second of precision, it can be identified to Coordinated Universal Time (UTC) which is the time used for hourly signals and broadcast clocks. The difference between TAI and UTC is an integer number of seconds.

* Zone Time

It is the Universal Time (UT) shifted with an integer number of hours.
Eastward Greenwich meridian : from UT+1h to UT+12h
Westward Greenwich meridian : from UT-1h to UT-12h

The difference between DT and UT can be deduced from the difference TAI-UTC given each year by IERS (International Service of the Earth Rotation). As for example, on 1986 Jan. 1, one has TAI-UTC = 30s. Hence : DT-UT = 62.184s

Since the representations of the planetary orbits are expressed in Dynamical Time, the program PLANEPH uses an "estimate" of the difference DT-UT when ephemeris have to be computed in Universal Time or in one another civil time. This "estimate" is provided in the Calendar (E9).

Origine Meridian :
The time scale determines the origine meridian of terrestrial longitudes.
It is Ephemeris meridian with Dynamical time (DT).
It is Greenwih meridian with Universal Time (UT) or civil times.
The Ephemeris meridian is 1.002737909*(DT-UT) east of the Greenwich meridian.

14. UNITS (U)
-------------------
Different choices of units are afforded for geometric, apparent, astrometric and topocentric coordinates.

Units of distances :
- Astronomical unit (au),
- Kilometer (km).

Units of angles :
- Sexagesimal hour/degree,
- Decimal hour/degree,
- Sexagesimal degree,
- Decimal degree,
- Radian.

Sexagesimal or decimal hours are proposed in the following cases :
- Equatorial coordinates (geometric, apparent or astrometric right ascension),
- Horizontal coordinates (azimuth),
- Hour angles.

The time unit of the velocities for geometric ephemeris (E1) is always the day.

15. RESULTS (R)
-------------------------
Results are displayed either in interactive or in sequential mode.

* R1 : Interactive display
0
The ephemeris are computed for the chosen initial date, as well as for the previous or the following dates, depending on the tab interval.

With the keys "+" and "-" the user can compute and display ephemeris for the following (+) and previous (-) dates.

It is possible to change tab interval (I) in order to center the ephemeris on the date in the middle of the displayed outputs.

At the end of the computation, the initial date is the central value displayed on the screen.

* R2 : Sequential display

The ephemeris are computed sequentially starting at the initial date, and with the chosen tab interval.

The number of dates of the ephemeris is defined by the user (maximum : 999).

At the exit (Q), the initial date and tab interval remain unchanged, and the user can view the whole set of results with the keys "+" and "-" for following and previous dates, "S" and "E" for Start and End of the ephemeris.

With the key "B" the user can save his results on a Backup file at his convenience.

At the first use, the name of the file which is proposed is : planeph.res.

The backup file is registered in the current directory. Several files can be created to save various ephemeris. If a file already exists to save new outputs, results are appended on that file.
Backup files contain page skip characters (Ctrl-L) for printing.

16. END OF THE PROGRAM (Q)
------------------------------------------------
The command Q in the main menu allows to quit the program. The user has to confirm his request, and is able to save the specifications of the last computation to reallocate them for a further run of the program.

In case of FATAL ERROR during the computation of the program, a message requests the user to quit the program. He may report to the authors the informations contained in the file : planeph.err.

17. SUPPLEMENTARY FILES
-------------------------------------------
Several files are created during a run of the program, in the current directory :

* File : planeph.prm.
The file contains the specifications of the last computation before leaving the application, if the user has chosen this option.

* File : planeph.tmp.
The file is created when the user chooses a sequential display of the results (R2). It is automatically scratched at the end of the program unless an abnormal termination.

* File planeph.res.
This is the file which is proposed to the user when saving sequential results (R2). At the end of the program, the user has to handle the backup files created during the application : printing, copy, scratch ,...

* File planeph.err.
This file contains the parameters of the computations in case of a FATAL ERROR.

18. PRECISION
------------------------
The precision of the representation used for the computation of the planetary ephemeris can be estimated by the largest discrepancies obtained with a comparison to the original ephemeris DE403, which are used as source.

Geometric equatorial coordinates J2000

Body Heliocentric Geocentric

19. CONSTANTS
-------------------------
Standard epoch J2000 1/1/2000 0h DJ2451545.0
Julian century 36525 days
Astronomical unit 149597870.691 km (DE403)
Light time (1 au) 0.577551833 d/au
Earth Equatorial radius 6378.137 km (DE403)
Oblateness of the Earth 0.335281

Gm = k2 * Mass(Body) / Mass(Sun) ; source : DE403

Sidereal time : Aoki et al., 1982, The New Definition of Universal Time, Astron.& Astrophys., 105, 359.

Precession : Lieske et al., 1977, Expressions for the Precession Quantities Based upon the IAU (1976) System
of Astronomical Constants, Astron.& Astrophys., 58, 1.

Nutation : IAU 1980 Theory of Nutation, J. M. Wahr, 1981, The forced nutation of an elliptical, rotating, elastic and oceanless earth, Geophys. J. R. astr. Soc., 64, 705.

Refraction : Tables de R. Radau, Annales de l'Observatoire de Paris. Tome XIX.

Planetary elements : Davis M.E. et al., 1992, Report of the IAU/IAG/COSPAR Working Group on cartographic coordinates and rotation elements of planets and satellites : 1991, Celest. Mech., 53, 377.

Magnitudes : Harris D.L., 1961, Photometry and Colorimetry of Planets and Satellites, Planets and Satellites, G.P. Kuiper and B.A. Middlehurst eds. University of Chicago Press, 272.

20. REFERENCES
---------------------------
Chapront J., 1995, Representation of planetary ephemerides by frequency analysis, Astron.& Astrophys. Suppl. Series, 109, 181.

Standish E.M., Newhall X.X., Williams J.G., Folkner W.M., 1995, JPL Planetary and Lunar Ephemerides DE403/LE403.
Interoffice Memorandum, IOM 314,10 - 127 Jet Propulsion Laboratory.

Chapront J., Francou G., Rocher P., Representation of an ephemeris by frequency analysis. Applications to planets and satellites. IAU Colloquium 165, Poznan, Poland (July 1996).

Il existe une version Word 97 nommée ephemeri.doc